home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
INFO
/
QUIKHELP.ZIP
/
QHCOMPIL.DOC
< prev
next >
Wrap
Text File
|
1988-06-08
|
33KB
|
674 lines
QHCOMPIL - The Help File Compiler for QHELP
Help File Programmer's Guide
Written by
Mark VanKekerix
2035 J Apt 6
Lincoln, NE 68510
(402) 475-0601
QHELP and QHCOMPIL software Copyright 1988 by Mark VanKekerix
TABLE OF CONTENTS
License
Introduction
Writing Help Files for QHELP
Overview
Reserved Characters (and How to Use Them)
Defining a Default Screen
General Guidelines and Restrictions
Using QHCOMPIL (the Help File Compiler)
Overview
Changing the Hot Key
Changing the Display Attributes
Changing Case Sensitivity
Changing the Description Indentation
Setting the Identifier Characters
Updating Header Information (on an Existing File)
Reading Header Information (from an Existing File)
Compiling a Help File
Uncompiling a Help File
Compiler Errors and Warnings
Acknowledgements
NOTE: It is assumed in this manual that you are reasonably familiar with
the use of QHELP. If you have never used QHELP before, read the
QHELP Users Guide and try running QHELP to familiarize yourself
with it before writing any help files. There should be a sample
help file distributed with QHELP that is already compiled and ready
for you to use.
LICENSE
Users of the QHELP system are granted a limited license for personal use. No
part of the QHELP system can be distributed for profit without a specific
written agreement (this includes distribution within a company or
corporation, "bundling" with other software, etc.). These limitations apply
to QHELP, QHCOMPIL (the help file compiler), and any help files created with
QHCOMPIL.
What this means is you are free to use QHELP and any help files you have
created yourself or obtained from bulletin boards, etc., but if you want to
package QHELP with another program you are selling for profit, contact me for
written permission to do so (I will ask for a small fee for such a license).
The limitation on "bundling" QHELP with other programs applies only if the
program is being sold for profit. If you have developed a public domain
program and would like to use QHELP and a help file you have written as the
program's help system, please feel free to do so.
If you have written a help file for any program (public domain or otherwise)
that you think other people would find helpful, I encourage you to make it
part of the public domain (along with a copy of QHELP).
I also encourage you to upload QHELP and QHCOMPIL to all of your favorite
bulletin boards, copy it for your friends, etc., as long as you don't violate
the above restrictions.
QHELP may be distributed by itself (without QHCOMPIL) subject to the above
restrictions. If you are going to distribute QHELP in such a manner, please
make sure the QHELP Users Guide and at least one compiled help file are
included. If you are going to distribute the full QHELP system, please make
sure that ALL the files you recieved (including the Users Guide and this
document) are included in your distribution.
INTRODUCTION
This manual is going to assume that you are already familiar with the use of
QHELP, and that you would now like to write some of your own help files.
Before reading further you should know a couple of terms that this manual
will use.
A "source file" is the file you will create with your text editor. It will
contain all the help information you want in your help file, organized in a
such a way that QHCOMPIL understands how you want the information displayed
by QHELP. Creating source files is discussed in the section "Writing Help
Files".
A "help file" is the file created by QHCOMPIL from your source file. It
consists of several parts. First, a header record that defines the hot key,
text colors, and several other things. Second, a list of the keywords
defined in your source file along with pointers to where the keyword
descriptions are located in the file (this allows QHELP to access help
information quickly even if the help file is very large). Last, and most
important, the actual descriptions for the keywords along with some
information on how to properly display it in the QHELP window. You don't
really need to fully understand the help file structure because QHCOMPIL
takes care of all the messy details of creating it.
"Reserved characters" are characters that you will use in your source file to
tell QHCOMPIL how to define the keywords and how you want descriptions for
the keywords displayed. The reserved characters that QHCOMPIL uses are
described in the section on "Writing Help Files".
A "default screen" is the display that appears when QHELP can't find a
keyword at the cursor position, or when you press the <F1> key while QHELP is
popped up. This is often a simple list of the available keywords, but it can
be more complex (and more useful) if you define it properly.
"Related keywords" are simply other keywords that relate to a given keyword.
Related keywords are displayed in a highlighted color in keyword
descriptions, and the user is allowed to select a related keyword while
viewing the keyword description.
Any text editor can be used to create source files, as long as the file
created is a simple text file (so it doesn't contain any sort of "formatting"
characters, such as tabs, etc.). Most word processors have either a "non-
document" mode (that results in the same sort of simple text file) or a
utility to convert a document to a simple text, or ASCII, file.
To obtain a sample source file, try using the "Uncompile" option of QHCOMPIL
on the sample help file included with QHELP.
WRITING HELP FILES
Overview
There are two types of reserved characters: Those that are recognized
only when they appear at the begining of a line, and those that are
recognized anywhere within a line. If a reserved character that is only
recognized at the beginning of a line appears anywhere else, it is
simply treated as part of the text describing a keyword. If you must
have a reserved character as part of your text in a position where it
would be used by the compiler, simply put two such characters in that
place. Any pair of reserved characters signals QHCOMPIL that the
character must appear there as text, and QHCOMPIL will place ONE of the
characters correctly.
The following are the reserved characters:
Name Character Position
Define Keyword : Beginning of line
Page End ! Beginning of line
Comment @ Beginning of line
Define Title # Beginning of line
Reference Keyword ~ Anywhere
The format of the source file is fairly simple. You simply define a
keyword on a line starting with the Define Keyword character ':', and
any lines that follow (up to the next Define Keyword line or the end of
the source file) will be the description for that keyword.
Reserved Characters (and How to Use Them)
The Define Keyword character ':' must appear at the beginning of a line,
and the keyword to define MUST immediately follow (no spaces between the
':' and the keyword). Null keywords (a ':' with no keyword behind it)
are not allowed. All text on the lines following a keyword definition
up to the next keyword definition or the end of the file comprise the
description for that keyword.
If the description is longer than the QHELP window size, QHCOMPIL will
break the description into pages that will fit in QHELP's window. If
you have a long description that you know will be paged and you want to
define the page endings yourself, use the Page End character '!'. This
character must appear at the beginning of a line, and all text behind
the '!' on that line is completely ignored (not included in the
description). When QHCOMPIL reaches the end of a description (the next
keyword definition or end of file) it automatically ends the current
page, so don't add a Page End character at the end of your description
or you will be rewarded with a blank page.
If your source file is very long, it might be wise to add some comments
to it to help you remember its organization when you later try to change
it. Comments are simply lines that begin with the Comment character
'@'. This character must appear at the beginning of the line, and all
text behind it is ignored. Comments can appear anywhere in the source
file.
The Define Title character '#' defines a title for the help file that
appears on the top line of the QHELP window when popped up. The first
20 characters following the Define Title character are used to form the
title. The Define Title character also defines the default screen; The
next keyword definition following a Define Title line is taken as the
"default keyword" for the file. This means that the display defined for
the "default keyword" is the one that appears when QHELP can't find a
keyword at the cursor, or when the <F1> key is pressed while QHELP is
popped up. For more information on defining a default screen, see the
subsection "Defining a Default Screen" later in this section. Only the
first occurence of a Define Title line is valid; further occurences are
ignored and treated as comments.
The Reference Keyword character '~' is perhaps the most useful reserved
character. This character can appear anywhere in a keyword
description. Immediately following this character should be a word that
is or will be defined as a keyword. When QHCOMPIL sees this character,
it assumes that the word following it is a keyword related to the
keyword being described, and QHCOMPIL will insert into the help file the
proper information for QHELP to display this word in a highlighted color
and allow it to be selected. The word following the Reference Keyword
character MUST be defined as a keyword at some point in the source file,
or errors will result when the file is compiled. However, the
referenced keyword does not have to be defined before it is referenced
(its definition may appear later in the source file).
Defining a Default Screen
When the first occurence of a Define Title line is found, the NEXT
keyword definition is taken as the "default keyword" for the help file,
and the keyword description for it becomes the default screen. The
default screen appears when QHELP can't find a keyword at the cursor or
when the <F1> key is pressed while QHELP is popped up. The default
screen is defined the same way any other keyword description is defined,
however you should make sure that the user will know that this is the
default screen.
One possibility for a default screen is a simple message that no keyword
was found at the cursor, and that the user should press <ESC>.
A better idea is a complete list of keywords, with each keyword in the
list defined as a referenced keyword. This presents a list of
highlighted and selectable keywords to the user when no keyword is found
at the cursor. For example:
#Title For File
:KEYWORDLIST
Available keywords
~KEY1
~KEY2
~KEY3
~KEY4
Placing these lines at the top of your source file will create a default
screen consisting of a list of four keywords that the user can select
from. Note that "~KEYWORDLIST" does not appear in the list; While this
is a valid reference (there is nothing preventing a keyword description
from referencing itself) it is pointless, since selecting this keyword
will simply cause the list to reappear.
If the list of keywords is very long, QHCOMPIL will break it into pages
that will fit in the QHELP window (or you can create the pages yourself
with the Page End character).
Another idea for a default screen is to create a "menu" structure by
defining keywords that contain (as their description) sub-lists of the
complete list of keywords. In this way, you can break down the list of
keywords into logical groups. For example:
#Title For File
:MAINMENUKEY
Select a Group
~GROUP1
~GROUP2
~GROUP3
:GROUP1
Select a Keyword
~KEY1
~KEY2
:GROUP2
Select a Keyword
~KEY3
~KEY4
~KEY5
:GROUP3
Select a Keyword
~KEY6
~KEY7
Placing these lines at the top of your source file will define a simple
menu structure that breaks down the list of keywords into three groups.
By selecting a group from the default screen, the user is presented with
a list of keywords from that group, and can then select the keyword
he/she was after. There is no limit to how "deep" such a menu structure
can go.
Notice that the group names are also defined as keywords, so you should
choose as your group names words that are not likely to be found at the
cursor.
General Guidelines and Restrictions
All keywords that are referenced with the Reference Keyword character
'~' MUST be defined at some point in the source file. Failure to define
a keyword that is referenced will result in a compiler error.
Keywords can't be defined more that once; If your source file
"redefines" a keyword, QHCOMPIL will generate a error.
No more than ten pages of text are allowed for any keyword description.
If a description has too many pages, QHCOMPIL will generate an error.
Each page can be up to fifteen lines long.
No more than 100 keywords can be referenced by any keyword description.
Having too many references results in a compiler error. Note that the
100 references can appear on any page of the description or be split
among the pages, but there can't be more than 100 in the entire
description.
No more than 500 keywords can be defined in a single help file.
Defining too many keywords generates a compiler error.
USING QHCOMPIL (THE HELP FILE COMPILER)
Overview
Once you have created your source file, you will need to compile it with
QHCOMPIL. QHCOMPIL allows you to define the header information for the
help file, compile and "un"-compile help files, and update the header of
a help file without re-compiling it. The header information consists of
several parts:
1) The "hot key" for popping up QHELP
2) The colors, or "attributes", of the text in the QHELP window
3) Whether the search for keywords at the cursor is case-
sensitive
4) The indentation for displaying description lines
5) Which characters (if any) besides letters and numbers can be
considered a part of a "word".
To run the help file compiler give the following command at the DOS
prompt:
QHCOMPIL
The QHCOMPIL menu will appear at the left side of the screen, and on the
right side will be the current settings for the header and an example of
the current attributes. To make selections from the menu, use the up
and down arrow keys on the numeric keypad to move a highlight bar to the
option you want, then press <ENTER>.
To exit QHCOMPIL, simply select the "Exit to Operating System" option
from the menu.
Changing the Hot Key
To change the "hot key" that will pop QHELP up, select the "Change Hot
Key" option from the QHCOMPIL menu. The hot key is defined in two
parts: The shift status and the scan code. The shift status is the
state that the four shift keys must be in (the four shift keys are the
<Alt> key, the <Ctrl> key, the left <Shift> key, and the right <Shift>
key). The scan code identifies the key (other than the shift keys) that
must be pressed when the shift status matches what QHELP is looking for.
When the "Change Hot Key" option is selected, a small window will appear
at the bottom of the screen that allows you to set the shift status.
The four shift keys and their status for the current hot key will be
shown. To change settings, move the highlight bar (with the arrow keys)
to the shift key whose status you want to change, and press <Enter>.
When you are finished setting the shift status, press <ESC>.
After setting the shift status, a window will appear that lists the
"names" of the keys on the keyboard that generate scan codes that QHELP
can use (these names are laid out to match the 84-key AT keyboard
layout). At the bottom of the window you will be asked for the name of
the key. You can enter the name of any key listed, or "NONE" if want to
pop up QHELP with a combination of only shift keys. After entering the
name of the key you will be returned to the QHCOMPIL menu and the window
at the upper right of the screen will be updated to show the hot key
combination that you just entered.
Note that in order for QHELP to pop up, the hot key combination must be
pressed EXACTLY. For example, if the hot key is [Alt]-F1, then the user
must press and hold ONLY the <Alt> key, then tap the <F1> key. If the
user were to press the [Alt]-F1 combination while holding down the
<Ctrl> key, QHELP would not pop up. The advantage to making the hot key
match exactly is that you have many more unique key combinations to
choose your hot key from.
Note also that by choosing "NONE" for a scan code you can pop QHELP up
with a combination of just shift keys. For example, you can set your
hot key to be [Alt][Ctrl][LShft], and QHELP will pop up whenever these
three keys (and no others) are pressed at the same time.
Changing the Display Attributes
When the "Change Attributes" option is selected, a small menu will
appear at the lower right of your screen listing the QHELP window
attributes that you can change. Select the option whose attribute you
want to change (using the arrow keys to move the highlight bar) and
press <Enter>. A large window will appear at the left side of your
screen that has a table of x's in it, each one displayed in a different
attribute combination. One of the x's will have a box around it. This
is the current attribute for the option you selected. Using the arrow
keys you can move the box around the window, and as you move the box,
the attribute example window on the right side of your screen will
change to show the option you selected in the attribute combination
given by the box. Pressing the <Enter> key selects the attribute in the
box for the given option and returns you to the list of options. If you
have moved the box but decided you don't want to change anything, press
the <ESC> key and the original attribute will be restored and you will
be returned to the list of options.
Note that the attributes you define for a help file apply only when
QHELP detects that the system is running in a color mode. If the system
is running in a black and white mode or is not capable of displaying
colors, QHELP's default black and white color scheme is used for
displaying the QHELP window.
When you are finished changing attributes, press the <ESC> key and you
will be returned to the QHCOMPIL menu.
Changing Case Sensitivity
Case sensitivity affects how QHELP compares the word it finds at the
cursor to keywords in the help file. For example, with case sensitivity
on, the words "Define" and "define" are considered DIFFERENT words. If
case sensitivity is off, "Define" and "define" are considered the same
word. The current state of case sensitivity is shown in the current
settings window at the upper right of your screen. Selecting the
"Change Case Sensitivity" option of the QHCOMPIL menu will "toggle" the
case sensitivity on and off.
Changing the Description Indentation
The description indentation is the number of spaces inserted at the
beginning of each line of a description when it is displayed in the
QHELP window. Selecting the "Change Indentation" option from the
QHCOMPIL menu will cause a small window to appear on your screen that
asks you for the indentation. Enter the number of spaces to indent and
press <ENTER>. An indentation of 2 or 3 is usually good enough (this is
just enough to move the text away from the edge of the window). After
entering the indentation, you will be returned to the QHCOMPIL menu.
Setting the Identifier Characters
Identifier characters are characters other than letters and numbers that
QHELP considers part of words. For example, it is common in some
computer programming languages to use the underline character as part of
identifier names, as in "_status" (which might be a variable name). To
change the list of characters that QHELP will use in determining what is
and isn't a word, select the "Set Identifier Characters" option from the
QHCOMPIL menu. A small window will appear that asks for a list of
identifier characters. Type in ALL the characters you want in this list
(if you simply want to add to the list that already appears in the
current settings window, you must retype all the characters that are
there in addition to the one you want to add). When entering these
characters do NOT put spaces between them (if you do, the space
character will be added to the list also). When the list is complete,
press <Enter> and you will be returned to the QHCOMPIL menu with the
current settings window updated to reflect the new list. Up to 10
additional identifier characters may be defined.
Updating Header Information (on an Existing File)
If your goal is simply to change the header information on an existing
help file, you don't need to recompile the source file. Change the
header information in the current settings window to match what you want
for the help file using the first five options on the QHCOMPIL menu,
then choose the "Update Help File Header" option. A small window will
appear that asks you for the help file to update. Enter the help file
name without an extension (".QHP" is assumed) and press <Enter>. If
QHCOMPIL can't find the help file, a message to that effect will
appear. If the help file exists, you will be warned that updating the
header will permanently change the help file, and you will be asked to
confirm that you want this done. Press 'Y' to confirm, 'N' to abort the
operation. You will then be returned to the QHCOMPIL menu.
Reading Header Information (from an Existing File)
This option is useful if you are making a single change to the header
information of a help file and don't want to re-enter all the other
header information or if you are developing a large help file and will
be compiling it several times and you don't want to re-enter all the
header information every time. What this option does is loads the
header information from an existing help file and changes all the
settings in the current settings window to match that header
information.
Select the "Read Help File Header" option from the QHCOMPIL menu. A
small window will appear that asks for the name of the help file from
which to get the header information. Enter the help file name without
extension (".QHP" is assumed) and press <Enter>. If QHCOMPIL can't find
the help file, a message to that effect will appear, otherwise you will
be returned to the QHCOMPIL menu with the current settings changed to
match the specifed help file header.
Compiling a Help File
This option is the heart of QHCOMPIL. When the "Compile Help File"
option is selected, a large window appears on your screen. You are
first prompted for the name of the source file. When entering the
source file name, you must include the extension (no extension is
assumed for source files). If QHCOMPIL can find the source file, it
asks for the name of the help file to create. When entering the help
file name, do NOT include the extension (".QHP" is assumed).
After both filenames are entered, QHCOMPIL will begin compiling the
source file. As the compiler works, you will see messages in the window
that tell you what it is doing. If an error occurs, compilation will
halt and an error message will appear in the window, along with some
information on where in the source file the error occured. You may also
see some warnings, but these will not halt the compilation process.
When compilation is complete or when an error occurs you will be asked
to press <ESC>. This will return you to the QHCOMPIL menu.
Uncompiling a Help File
Uncompiling a help file is the reverse of compiling a source file; it
takes a help file and creates a source file from it. When the
"Uncompile Help File" option is selected, you will be asked for the name
of the help file to uncompile. Enter this name without an extension
(".QHP" is assumed). You are then asked for the name of the source file
to uncompile to. Enter this file name WITH an extension (no extension
is assumed for source files).
After both filenames have been entered, QHCOMPIL will begin uncompiling
the help file. When the process is complete, you will be returned to
the QHCOMPIL menu.
The source files that result from uncompiling a help file will not
exactly match the original source file, since the help files don't store
things like comments, etc. However, the resulting source file can be
recompiled to obtain exactly the same help file. Also, the uncompile
option will place several comments at the beginning of the resulting
source file that indicate the settings of the header information for the
help file.
Compiler Errors and Warnings
When compiling a help file QHCOMPIL may generate warning messages.
These warnings do not stop compilation, but you should be aware of
them. QHCOMPIL will generate a warning for every keyword that is
defined but not used as a reference by some other keyword (that is, the
keyword description is only available by popping QHELP up with that word
under the cursor, and it will never appear as a highlighted word in
another keyword description or a keyword list). This is perfectly
legal, but it isn't always a good idea. If you have created a list of
keywords as your default keyword description, you should take note of
these warnings (note that the default keyword itself will appear in this
list of warnings, but it can be safely ignored since it is not intended
to be referenced).
QHCOMPIL may also encounter errors in the source file. Any error will
halt the compilation process, and a message will be printed describing
the error, along with some information to help you locate the error in
your source file. QHCOMPIL will only "see" the first error in a source
file; If other errors exist, you will need to fix the current error and
recompile the source file to find the next one.
The following is a list of QHCOMPIL error messages. Most of these
messages are self-explanatory, but where appropriate some additional
information is given. The number at the left is the internal QHCOMPIL
error number, so the numbering may have gaps but this list is complete.
2) Error writing output file.
3) Unable to resolve keyword reference.
This error occurs when you have referenced a keyword with the
Reference Keyword character '~' but have not defined the
keyword being referenced anywhere else in the source file.
4) Unable to open input file.
This error may occur if the source file exists but has been
locked by some other program.
5) No title screen defined.
QHCOMPIL didn't find a Define Title line anywhere in the
source file, and therefore can't define a default screen.
12) Keyword too long in line XX
The keyword being defined exceeds the maximum keyword length
of 15 characters.
13) Maximum keywords exceeded in line XX
You have tried to define more than 500 keywords in the source
file.
14) Not enough available memory in line XX
15) Line too long in line XX
The description line is too long to fit in the QHELP window.
Note that the indentation defined as part of the header is
added to the beginning of each line as it is compiled, so the
line may LOOK like it will fit, but adding the indentation
makes it too long.
16) Too many keyword references in line XX
You have tried to reference more than 100 keywords in a
keyword description.
17) Too many pages for description in line XX
The keyword description exceeds 10 pages.
18) Text not associated with keyword in line XX
This error will occur at the beginning of a source file if
QHCOMPIL sees what appears to be part of a description but no
keyword has been defined yet.
19) Null keywords not allowed here in line XX
A Define Keyword character appears with no keyword behind it.
20) Keyword redefinition in line XX
This error occurs when QHCOMPIL sees a keyword definition for
a keyword that was defined earlier in the source file.
XX) Unknown error XX in line XX
This error occurs when an internal QHCOMPIL error is generated
that QHCOMPIL doesn't recognize.
ACKNOWLEDGMENTS
I would like to thank Borland International both for its outstanding "C"
compiler, TurboC, and for the excellent help system in TurboC's integrated
development environment which inspired me to write QHELP.
I would also like to thank Al Stevens for his article "Writing Terminate-and-
Stay-Resident Programs (Part 1: TSRs in TurboC)" in Computer Language
magazine (February 1988 issue). In that article Mr. Stevens gave complete
listings for the shell of a resident program, and these are the residency
routines that QHELP uses (with some minor modifications). Anyone interested
in trying his/her hand at writing resident programs (in "C" or otherwise)
would do well to read Mr. Stevens' article.
Also, special thanks go out to my roommate, Dave Steiner. Since he is an
experienced "C" programmer and has also written many resident programs (in
several languages), I pestered him with endless questions and he somehow
managed to answer them all. Oh, and I used a "C" library written by Dave
for all the menus and windows in QHCOMPIL.